Skip to content

Improve markdown files and add markdownlint#138

Merged
Xymph merged 4 commits intomasterfrom
markdown-improvements
Aug 31, 2021
Merged

Improve markdown files and add markdownlint#138
Xymph merged 4 commits intomasterfrom
markdown-improvements

Conversation

@waldyrious
Copy link
Copy Markdown
Collaborator

@waldyrious waldyrious commented Aug 31, 2021 •
edited
Loading

  • Normalize headings in markdown files: start each file with a h1-level heading, and increment levels for section headings one at a time. These correspond to rules MD041 and MD001 of markdownlint, respectively.
  • Assorted improvements to markdown files:
    • Add introductory context
    • Reword the introductory paragraphs of GOVERNANCE.md into a proper section
    • Fix a typo in CONTRIBUTING.md
    • Apply various fixes recommended by markdownlint
    • Change list syntax in markdown files (use dashes for lists, and leave asterisks for emphasis, as first proposed here)
  • Add a GitHub Action to run markdownlint on markdown files in pull requests

@waldyrious waldyrious force-pushed the markdown-improvements branch 2 times, most recently from 360b26d to 2f722c0 Compare August 31, 2021 18:36
@waldyrious waldyrious mentioned this pull request Aug 31, 2021
Merged
@waldyrious waldyrious force-pushed the markdown-improvements branch from 2f722c0 to e1a9825 Compare August 31, 2021 18:53
@waldyrious waldyrious marked this pull request as ready for review August 31, 2021 18:54
@waldyrious waldyrious requested a review from Xymph August 31, 2021 18:54
@waldyrious
Normalize headings in markdown files
e27fd2f 
Start each file with a h1-level heading,
and increment levels for section headings one at a time.

These correspond to rules MD041 and MD001 of markdownlint, respectively.
@waldyrious waldyrious force-pushed the markdown-improvements branch from e1a9825 to d8dd918 Compare August 31, 2021 19:05
@waldyrious waldyrious changed the title Improve markdown files Improve markdown files and add markdownlint Aug 31, 2021
Xymph
Xymph requested changes Aug 31, 2021
View reviewed changes
Copy link
Copy Markdown
Collaborator

@Xymph Xymph left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good improvements, with some nice touches like the text type for the Array example.
One more tweak: https://github.com/hamstar/Wikimate/blame/503625f9e2c23a442d8bda368c4974281c2bd1f3/GOVERNANCE.md#L46
Change "the README" into "README.md"

@Xymph
Copy link
Copy Markdown
Collaborator

Xymph commented Aug 31, 2021

General question: how did you add the remarks below the commit message, e.g. "Use dashes for lists..." ?

@waldyrious
Improvements to markdown files
b7c4432 
- Add introductory context
- Reword the introductory paragraphs of GOVERNANCE.md into a proper section
- Fix a typo in CONTRIBUTING.md
- Apply various fixes recommended by markdownlint
@waldyrious
Change list syntax in markdown files
76cc5df 
Use dashes for lists, and leave asterisks for emphasis.
@waldyrious
Add GitHub Action to run markdownlint in markdown files
6dd37f2
@waldyrious waldyrious force-pushed the markdown-improvements branch from d8dd918 to 6dd37f2 Compare August 31, 2021 20:18
@waldyrious
Copy link
Copy Markdown
Collaborator Author

waldyrious commented Aug 31, 2021 •
edited
Loading

One more tweak: https://github.com/hamstar/Wikimate/blame/503625f9e2c23a442d8bda368c4974281c2bd1f3/GOVERNANCE.md#L46
Change "the README" into "README.md"

Done :)

General question: how did you add the remarks below the commit message, e.g. "Use dashes for lists..." ?

A git commit message can have a summary and a body, though most of the time only the former is used, which leads to the conflation of the expression "commit message" with the summary alone. But, as I alluded to recently, there is a recommended maximum length for the summary, so in many cases it's useful to provide additional details in the body.

In practice, the way you add content to the commit message body is by making a multi-line commit message, with a blank line separating the summary and the body. In the command line, simply typing enter before closing the quotes will allow you to add additional lines to the string:

$ git commit -m "Lorem ipsum↵
> ↵
> Dolor sit amet, consectitur adipisci elit."↵

GitHub will display commit message bodies as expandable notes with the "..." sign, as you see above.

@Xymph Xymph merged commit 82e27f7 into master Aug 31, 2021
@Xymph
Copy link
Copy Markdown
Collaborator

Xymph commented Aug 31, 2021

And that's another wrap. 👍

@waldyrious waldyrious deleted the markdown-improvements branch August 31, 2021 22:05
@waldyrious waldyrious mentioned this pull request Jul 21, 2023
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Xymph Xymph Xymph approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@waldyrious @Xymph